import { Meta, Status, Props, Story } from '../../../../.storybook/components';
import * as Stories from './ListItem.stories';

<Meta of={Stories} />

# ListItem

<Status variant="stable" />

The `ListItem` component is used to represent data in a structured and concise manner.

It covers various levels of complexity by being split into several designated areas that can hold textual, presentational or interactive components. In its simplest form, the `ListItem` only requires a label.

While the `ListItem` can be used on its own, in most cases the `ListItemGroup` component should be used to render a list of items.

<Story of={Stories.Base} />
<Props />

## Usage guidelines

- **Do** use the `navigation` variant when the items are links to other parts of the application or open a side panel.

## Content guidelines

- **Do** use size `24` Circuit UI icon, a custom 48x48 image, or other similar sized components, such as a circular Badge, for the `leadingComponent` if applicable.
- **Do** use the default styles for `label`, `details`, `trailingLabel` and `trailingDetails` by passing a string instead of a custom component.
- **Do** use size `one` Body for the `label` and `trailingLabel` when using a custom component if applicable.
- **Do** use size `two` subtle Body for the `details` and `trailingDetails` when using a custom component if applicable.
- **Do** use `&middot;` to split the `details` line in two sections if applicable.
- **Do not** use `trailingDetails` on their own without also providing a `trailingLabel`.
- **Do not** use a `trailingLabel` together with a custom `trailingComponent`. Add a label to the `trailingComponent` directly instead.

### Variants

In addition to the default `action` variant there is also the `navigation` variant.

It renders a chevron icon in the trailing area of the `ListItem`, indicating to the user that clicking on the item will either change the page or lead to a major change in the layout, such as opening a side panel.

<Story of={Stories.Variants} />

### Elements

A standard Circuit UI icon can be used as a `leadingComponent` to provide additional visual context to the user. The `leadingComponent` can also be used for custom components, such as a circular `Badge`.

<Story of={Stories.WithLeadingContent} />

When the `label` is provided as a string, it is rendered as a size `one` Body and is truncated when it gets too long. A custom component can be used for special cases, such as a multiline label.

<Story of={Stories.WithCustomLabel} />

The `details` line can be used to provide additional textual and visual information. It can be a string or a custom component.

<Story of={Stories.WithDetails} />

The trailing area can hold a combination of `trailingLabel` and `trailingDetails` or a standalone custom `trailingComponent`. The `trailingLabel` and `trailingDetails` can be custom components as well, but they should be used only for textual information.

<Story of={Stories.WithTrailingContent} />

The ListItem component becomes interactive when it receives an `onClick` or an `href` prop. This applies additional styles and accessibility features. Make sure to use the `navigation` variant when applicable, such as when the `ListItem` acts as a link.

<Story of={Stories.Interactive} />

With interactive list items it is also possible to set additional states like `selected` and `disabled`.

<Story of={Stories.Selected} />

<Story of={Stories.Disabled} />
